/*
XPTracker - Alternative Agile Tracking Tool
Copyright (C) 2006-2009  Stephen Starkey

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
*/
package org.xptracker.search;

import org.apache.lucene.document.Document;
import org.apache.lucene.document.Field;

import java.util.List;

/**
 * Creates {@link Document} instances used to index and search objects.
 * @author caliendo
 */
public interface IndexingHelper {

  /**
   * Return a {@link Document} for the passed object.
   * Indexable/SearchField fields on the object will be present in the {@link Document}.
   * @param obj
   *    the object to build a {@link Document} for
   * @return
   *    the {@link Document} for the passed object
   * @throws Exception 
   *    if an exception occurs while attempting to build a {@link Document} for the passed object
   */
  Document buildDocument(Object obj) throws RuntimeException;

  /**
   * Return the keywords for the specified class.
   * This will be the name of every {@link Field} 
   * in the {@link Document} returned by a call 
   * to {@link #buildDocument(Object)} with an object
   * of the same class.
   * @param clazz
   *    the class to determine the keywords for
   * @return
   *    the keywords for the specified class
   * @throws Exception 
   *    if an exception occurs while determining the keywords for the passed object
   * @see #buildDocument(Object)
   */
  List<String> loadQueryFields(Class clazz) throws RuntimeException;

  /**
   * Returns keywords as an array
   * @see IndexingHelper#loadQueryFields
   * @param clazz class to get keywords for
   * @return an array of query fields
   */
  String[] getQueryFields(Class clazz);

  /**
   * Return a bunch of search help objects.
   * @param clazz class to retrieve help objects from
   * @return a list of all the help objects for the search fields on the specified class
   */
  List<SearchHelp> loadHelpBeans(Class clazz);

  /**
   * Retrieve the field used to store the ID of the item
   * @param clazz name of the class
   * @return ID field name
   */
  String getIdField(Class clazz);

  /**
   * Get the value used to identify this item
   * @param obj item to get ID of
   * @return the ID of the item
   */
  String getId(Object obj);
}
